﻿<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
<html>
  <head>
    <title>PageMethods, well-defined URLs for your ASP.NET sites by metaSapiens</title>		
		<meta name="description" content="well-defined URLs for your ASP.NET sites, pragmatic software for a better world" />
		<meta name="keywords" content="dotnet tools .net asp.net url urls page pages parameter parameters microsoft c# vb vb.net" />
		<link href="index_files/PageMethods.css" type="text/css" rel="stylesheet" />
	</head>

  <body>
			<div style="margin-top: 25px;" align="center">
			<a href="http://metasapiens.com/PageMethods" title="well-defined URLs for your ASP.NET sites"><img src="index_files/PageMethods350.png" id="Img1" align="top" border="0" height="93" width="350" /></a>
			</div>
			<div align="center">
				<ul class="minitabs">
						<li><a href="http://metasapiens.com/PageMethods/Default.aspx" id="A1">Home</a> | 
  
						</li><li><a href="http://metasapiens.com/PageMethods/intro.aspx" id="A2">Introduction</a> | 
  
						</li><li><a href="http://metasapiens.com/PageMethods/features.aspx" id="A3">Features and benefits</a> | 
  
						</li><li><a href="http://metasapiens.com/PageMethods/Tutorial/" id="A4">Tutorial</a> | 
  
						</li><li><a href="http://metasapiens.com/PageMethods/technical.aspx" id="A5">Technical details</a> | 
  
						</li><li><a href="http://metasapiens.com/PageMethods/faq.aspx" id="A7">FAQ</a> | 

						</li><li><a href="http://metasapiens.com/PageMethods/download.aspx" id="A6">Download</a></li>
				</ul>			
			</div>
			
			<div style="margin: 10px 50px;">
				
<h1>Tutorial for Visual Studio 2005</h1>
<p>This tutorial demonstrates the use of <span class="PN">PageMethods</span> for 
VS 2005 through a step-by-step sample.</p>
<h2>Sample application</h2>
<p>We won't go into a complex application here. The goal is to demonstrate the 
use of <span class="PN">PageMethods</span> as simply as possible.<br />We will just 
consider two web pages, that should be sufficient to get an overwiew of the 
functionalities.</p>
<p>The first page will be used to edit details about a customer, or to create a 
new one. Let's name it <em>FrmCustomer.aspx</em>.<br />The second page will 
contain a list of the customers. That will be <em>ListCustomer.aspx</em>.</p>
<h2>Step by step</h2>
<h3>1 - FrmCustomer</h3>
<p>We will start by creating the <em>FrmCustomer</em> page.</p>
<p>First, make sure the <span class="PN">PageMethods</span> add-in is installed 
and activated.</p>
<p><img src="index_files/02.png"></p>
<p>Next, create a new web site named <em>PageMethodsTutorial</em>.</p>
<p><img src="index_files/01.png"></p>
<p>Add a new web form named <em>FrmCustomer.aspx</em>.</p>
<p><img src="index_files/04.png"></p>
<p>Let's say this page will enable specifying a name and a country for a 
customer.<br />Add three labels, three EditBox controls (txtID, txtName, 
txtCountry), and a button to the page, as follows:</p>
<p><img src="index_files/05.png"></p>
<p>We said this page would be used to edit details about a customer or to create 
a new one, so we will add two methods to the page that will represent these two 
ways to use the page.<br />Switch to the code view, and add the two methods:</p>
<p><img src="index_files/06.png"></p>
<p>Until now, all we have is standard code. We will add an attribute to these 
methods to start using <span class="PN">PageMethods</span>.<br />This requires 
adding a reference to the <span class="PN">PageMethods</span> Library 
(PageMethods.dll assembly).</p>
<p><img src="index_files/07.png"></p>
<p>Make sure you select the library for .NET 2.0. The version and the runtime 
may vary depending on the version you are using.</p>
<p>Let's use the <em>MetaSapiens.PageMethods</em> namespace:</p>
<p><img src="index_files/03.png"></p>
<p>Here is how to add the attributes:</p>
<p><img src="index_files/08.png"></p>
<p>We will now be able to refer to these methods from outside.<br />We still need 
to do a few last things before that.</p>
<p>Add a call to the <span class="PN">PageMethods</span> framework in the 
Page_Load event handler:</p>
<p><img src="index_files/09.png"></p>
<p>Activate <span class="PN">PageMethods</span> for this project.</p>
<p><img src="index_files/10.png"></p>
<p>Register <span class="PN">PageMethods</span>' custom build provider in the 
configuration file:</p><font color="#0000ff" size="2">
</font><p><font color="#0000ff" size="2"><font face="Courier New">&lt;?</font></font><font face="Courier New"><font color="#800000" size="2">xml</font><font color="#ff00ff" size="2"> </font><font color="#ff0000" size="2">version</font></font><font face="Courier New"><font color="#0000ff" size="2">="1.0"?&gt;<br />&lt;</font><font color="#800000" size="2">configuration</font></font><font face="Courier New"><font color="#0000ff" size="2">&gt;<br /><br />&nbsp; &lt;</font><font color="#800000" size="2">appSettings 
</font></font><font face="Courier New"><font color="#0000ff" size="2">/&gt;<br /></font></font><font face="Courier New"><font color="#0000ff" size="2"><br />&nbsp; &lt;</font><font color="#800000" size="2">system.web</font></font><font face="Courier New"><font color="#0000ff" size="2">&gt;<br />&nbsp;&nbsp;&nbsp; &lt;</font><font color="#800000" size="2">compilation</font><font color="#ff00ff" size="2"> </font><font color="#ff0000" size="2">debug</font></font><font face="Courier New"><font color="#0000ff" size="2">="true"&gt;<br />&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; &lt;</font><font color="#800000" size="2">buildProviders</font></font><font color="#0000ff" face="Courier New" size="2">&gt;<br />&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; 
&lt;</font><font face="Courier New"><font color="#800000" size="2">add<br /></font></font><font face="Courier New"><font color="#0000ff" size="2">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</font><font color="#ff0000" size="2">&nbsp;&nbsp;&nbsp; extension</font></font><font face="Courier New"><font color="#0000ff" size="2">=".xml"<br />&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; 
</font><font color="#ff0000" size="2">type</font></font><font face="Courier New"><font color="#0000ff" size="2">="MetaSapiens.PageMethods.PageMethodsBuildProvider, PageMethods" 
/&gt;<br />&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; &lt;/</font><font color="#800000" size="2">buildProviders</font></font><font face="Courier New"><font color="#0000ff" size="2">&gt;<br />&nbsp;&nbsp;&nbsp; &lt;/</font><font color="#800000" size="2">compilation</font></font><font face="Courier New"><font color="#0000ff" size="2">&gt;<br />&nbsp; &lt;/</font><font color="#800000" size="2">system.web</font></font><font color="#0000ff" size="2"><font face="Courier New">&gt;</font></font></p>
<p><font color="#0000ff" size="2"><font face="Courier New">&lt;/</font></font><font face="Courier New"><font color="#800000" size="2">configuration</font><font color="#0000ff" size="2">&gt;</font></font></p>
<p>Of course, you need to add a Web Configuration File (Web.config if your 
project does not already have one. If you already have an existing web.config 
file, make sure you put the extra data in the right place (under 
<strong>system.web/compilation</strong>).</p>
<p><strong>Compile</strong> to have <span class="PN">PageMethods</span> generate 
its magic code.</p>
<p>You won't see the generated code, but you may find the PageList.xml file 
located in the App_Code folder of the project. It is important that you never 
touch this file and leave it as is. <span class="PN">PageMethods</span> will 
manage it for you.</p>
<h3>2 - Referring to FrmCustomer</h3>
<p>The page we just created is only useful if we are able to access it, of 
course.<br />Usually, we would create a link to it using either an HTML anchor 
(&lt;A href=...&gt; tag) or the ASP.NET HyperLink control with a static value 
for the <em>NavigateUrl</em> property.</p>
<p>With <span class="PN">PageMethods</span>, we will use code-behind to take 
advantage of compile-time checks. This way we can be sure before deployment that 
the links we use are valid.</p>
<p>We will test this in the <em>Default.aspx</em> page.</p>
<p>Add a HyperLink control to the page.</p>
<p><img src="index_files/12.png"></p>
<p>Then set the HyperLink control's NavigateUrl as follows:</p>
<p><img src="index_files/14.png"></p>
<p>Hint: you can use the code completion to help you.</p>
<p>Linking to a page this way is easy because you can see the available pages 
and the ways to invoke them. It is also safer because you can get the guarantee 
at compile-time that your links are valid.</p>
<p>You can now test the link by running the <em>Default.aspx</em> page.</p>
<p>If you are not using Internet Explorer, you should deactivate the NTLM 
Authentication option in the project properties before.</p>
<p><img src="index_files/29.png"></p>
<p>Click on the link to test the navigation.</p>
<h3>3 - Improving FrmCustomer</h3>
<p>Some other attributes help you better define your query methods.</p>
<p>You can mark a parameter as mandatory using the 
<em><strong>ParamRequired</strong></em> attribute. This can be used with 
parameters that are not value types, such as String. Value types are always 
required because they cannot be null.</p>
<p><img src="index_files/16.png"></p>
<p>If no value is provided for a parameter marked as required or value type, an 
exception is raised.</p>
<p>The <em><strong>ParamName</strong></em> attribute can be used, in case you 
wish to specify the name used in the URL for a parameter, allowing parameter 
aliasing:</p>
<p><img src="index_files/17.png"></p>
<p>Now, the old <em>custID</em> parameter is changed to <em>CustomerID</em> in 
the links to this method.</p>
<p>For some types of parameters, a format string can be used. This is the case 
for data types implementing the <em><a href="http://msdn2.microsoft.com/library/bk5yxz0f%28en-us,vs.80%29.aspx" target="_blank">IFormattable</a></em> interface. <em>IFormattable</em> is 
implemented by the base data types, such as System.DateTime, System.Int32, or 
System.Guid. The <em><strong>ParamFormat</strong></em> attribute can be used to 
format a parameter.</p>
<p><img src="index_files/18.png"></p>
<p>Here we wish the parameter to be formatted on four digits.<br />Learn more 
about <a href="http://msdn2.microsoft.com/library/fbxft59x%28en-us,vs.80%29.aspx">formats and 
format strings on MSDN</a>.</p>
<h3>4 - ListCustomer</h3>
<p>The <em>ListCustomer</em> page contains a list of the customers.</p>
<p>Create a new page named <em>ListCustomer.aspx</em>.</p>
<p>Add a DataList control to the page.</p>
<p><img src="index_files/19.png"></p>
<p>Customize the DataList by editing the Item template.</p>
<p><img src="index_files/20.png"></p>
<p>An a HyperLink control to the ItemTemplate.</p>
<p><img src="index_files/21.png"></p>
<p>We will bind the DataList to a typed DataSet.<br />We need to create that 
DataSet:</p>
<p><img src="index_files/23.png"></p>
<p>Note that we do not need any connection or <em>TableAdapter</em>, but only a 
<em>DataTable</em> named Customer, with three fields: CustID 
(<em>System.Int32</em>), Name (<em>System.String</em>), Country 
(<em>System.String</em>).</p>
<p><img src="index_files/24.png"></p>
<p>Now, let's simulate some data coming from a database:</p>
<p><img src="index_files/25.png"></p>
<p>Add an event handler for the <em>ItemDataBound</em> event of the 
DataList.</p>
<p><img src="index_files/22.png"></p>
<p><img src="index_files/26.png"></p>
<p>This can also be done using databinding on the HyperLink instead. But we 
would not have the full benefits and so we do not recommend it.</p>
<p>You can now test the <em>ListCustomer</em> page and look at the links.</p>
<h2>More features</h2>
<h3>Base class for pages</h3>
<p>You noticed that we added a call to <em>PageMethodsEngine.InvokeMethod()</em> 
in the code for <em>FrmCustomer</em>. You could put that call in a base class 
for your pages, or have your pages inherit from the 
<em>MetaSapiens.PageMethods.BasePageWithDefaultMethod</em> or
<em>MetaSapiens.PageMethods.BasePageWithoutDefaultMethod</em> classes, which do just that. 
See the documentation about the above classes to learn more.</p>
<h3>Default method</h3>
<p>URLs managed with <span class="PN">PageMethods</span> have an additional 
parameter (named <em>PageMethod</em> by default) that is used to identify the 
target method during a page call. If there is only one method in the page or a 
main method, you can mark that method as the default method using 
<em>[PageMethod(true)]</em> instead of simply <em>[PageMethod]</em>. The result 
is that no additional parameter gets added to the URLs for that method.</p>
<h3>URL formatting</h3>
<p>If you are using URL rewriting (also called URL aliasing), you can provide 
<span class="PN">PageMethods</span> with a format string to format the URL for 
each method.</p>
<p>Let's take an example. With the following code,</p>
<p><img src="index_files/27.png"></p>
<p>a link to customer 12 would look like this: 
<em>http://myserver/PageMethodsTutorial/Pages/FrmCustomer.aspx?PageMethodsMethod=EditCustomer&amp;CustomerID=12</em></p>
<p>Using the <em><strong>PageMethods.UrlFormat</strong></em> attribute like 
this,</p>
<p><img src="index_files/28.png"></p>
<p>the same link would be like that instead: 
<em>http://myserver/PageMethodsTutorial/Customer12.aspx</em></p>
<p>You refer to a parameter using the {<em>parameter name</em>} syntax. You can 
refer to the method name using {{METHOD}}.</p>
<h2>Going further</h2>
<p>Basically, you've seen in this tutorial all that your need to know to be able 
to work with <span class="PN">PageMethods</span>.<br /><span class="PN">PageMethods</span> has more features than what is demonstrated here, 
but those will be explained somewhere else.</p>
<p>For example, if you want to see more code, you can take a look at the 
provided samples in C# and VB.NET.</p>
			</div>
			
			
			<div class="Footer">
				<span style="float: left; margin-right: 20px;">Copyright &copy; <a href="http://metasapiens.com/">metaSapiens</a>&nbsp;- Fabrice Marguerie</span>
				<a href="mailto:info@metaSapiens.com">e-mail contact</a>
			</div>

  </body>
</html>